2. Getting Started

2.1 Downloading and Installing

The first step to getting up and running with Grails is to install the distribution. To do so follow these steps:

If Grails is working correctly you should now be able to type grails in the terminal window and see output similar to the below:


Welcome to Grails 1.0 - http://grails.org/
Licensed under Apache Standard License 2.0
Grails home is set to: /Developer/grails-1.0
No script name specified. Use 'grails help' for more info

2.2 Creating an Application

To create a Grails application you first need to familiarize yourself with the usage of the grails command which is used in the following manner:

grails [command name]

In this case the command you need to execute is create-app:


grails create-app helloworld

This will create a new directory inside the current one that contains the project. You should now navigate to this directory in terminal:


cd helloworld

2.3 A Hello World Example

To implement the typical "hello world!" example run the create-controller command:


grails create-controller hello

This will create a new controller (Refer to the section on Controllers for more information) in the grails-app/controllers directory called HelloController.groovy.

Controllers are capable of dealing with web requests and to fulfil the "hello world!" use case our implementation needs to look like the following:

class HelloController {
	def world = {
		render "Hello World!"
	}
}

Job done. Now start-up the container with another new command called run-app:


grails run-app

This will start-up a server on port 8080 and you should now be able to access your application with the URL: http://localhost:8080/helloworld

The result will look something like the following screenshot:

This is the Grails intro page which is rendered by the web-app/index.gsp file. You will note it has a detected the presence of your controller and clicking on the link to our controller we can see the text "Hello World!" printed to the browser window.

2.4 Getting Set-up in an IDE

IntelliJ IDEA

Currently by far the most mature and comprehensive Groovy & Grails IDE is IntelliJ IDEA 7.0 and the JetGroovy plug-in. The Grails team recommends IDEA over other IDE environments for large projects.

TextMate

Since Grails' focus is on simplicity it is often possible to utilize more simple editors and TextMate on the Mac has an excellent Groovy/Grails bundle available from the Texmate bundles SVN.

Eclipse

For Eclipse there is also the Groovy Eclipse Plugin that offers syntax highlighting, code completion and so on.

There are some quirks with the Groovy Eclipse plug-in which are covered in detail on the Grails wiki.

Grails automatically creates Eclipse .project and classpath files for you, so to import a Grails project just right-click in the "Package Explorer" and select "Import" then "Existing project into Workspace" and "Browse" to the location of your project.

Then immediately click "Ok" followed by "Finish" and your project will be set-up.

Grails will also automatically set-up an appropriate Eclipse "Run Configuration", that can be accessed from the "Run" menu in Eclipse.

2.5 Convention over Configuration

Grails uses "convention over configuration" to configure itself. This typically means that the name and location of files is used instead of explicit configuration, hence you need to familiarize yourself with the directory structure provided by Grails.

Here is a breakdown and links to the relevant sections:

2.6 Running an Application

Grails applications can be run with the built in Jetty server using the run-app command which will load a server on port 8080 by default:

grails run-app

You can specify a different port by using the server.port argument:

grails -Dserver.port=8090 run-app

More information on the run-app command can be found in the reference guide.

2.7 Testing an Application

The create-* commands in Grails automatically create integration tests for you within the test/integration directory. It is of course up to you to populate these tests with valid test logic, information on which can be found in the section on Testing. However, if you wish to execute tests you can run the test-app command as follows:

grails test-app

Grails also automatically generates an Ant build.xml which can also run the tests by delegating to Grails' test-app command:

ant test

This is useful when you need to build Grails applications as part of a continuous integration platform such as CruiseControl.

2.8 Deploying an Application

Grails applications are deployed as Web Application Archives (WAR files), and Grails includes the war command for performing this task:

grails war

This will produce a WAR file in the root of your project which can then be deployed as per your containers instructions.

NEVER deploy Grails using the run-app command as this command sets Grails up for auto-reloading at runtime which has a severe performance and scalability implication

When deploying Grails you should always run your containers JVM with the -server option and with sufficient memory allocation. A good set of VM flags would be:

-server -Xmx512M

2.9 Supported Java EE Containers

Grails supports a pretty wide range of containers including:

Some containers have bugs however, which in most cases can be worked around. A list of known deployment issues can be found on the Grails wiki.

2.10 Creating Artefacts

Grails ships with a few convenience targets such as create-controller, create-domain-class and so on that will create Controllers and different artefact types for you.
These are merely for your convenience and you can just as easily use an IDE or your favourite text editor.
For example to create the basis of an application you typically need a domain model:

grails create-domain-class book

This will result in the creation of a domain class at grails-app/domain/Book.groovy such as:

class Book {	
}

There are many such create-* commands that can be explored in the command line reference guide.

2.11 Generating an Application

To get started quickly with Grails it is often useful to use a feature called Scaffolding to generate the skeleton of an application. To do this use one of the generate-* commands such as generate-all, which will generate a controller and the relevant views:

grails generate-all Book